<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>README.rdoc</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/github.css" type="text/css" media="screen" />
<script src="../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>     
    <div class="banner">
        
            <span>Ruby on Rails v4.0.0</span><br />
        
        <h1>
            README.rdoc
        </h1>
        <ul class="files">
            
            <li>
                actionmailer/README.rdoc
                
                    <a href="https://github.com/rails/rails/blob/5ba1b594aa866020fb62b961fae61a09529092a4/actionmailer/README.rdoc" target="_blank" class="github_url">on GitHub</a>
                
            </li>
            <li>Last modified: 2013-06-25 14:39:21 +0000</li>
        </ul>
    </div>

    <div id="bodyContent">
        <div id="content">
  
    <div class="description">
      
<h1 id="label-Action+Mailer+--+Easy+email+delivery+and+testing">Action Mailer – Easy email delivery and testing</h1>

<p>Action Mailer is a framework for designing email service layers. These
layers are used to consolidate code for sending out forgotten passwords,
welcome wishes on signup, invoices for billing, and any other use case that
requires a written notification to either a person or another system.</p>

<p>Action Mailer is in essence a wrapper around Action Controller and the Mail
gem.  It provides a way to make emails using templates in the same way that
Action Controller renders views using templates.</p>

<p>Additionally, an Action Mailer class can be used to process incoming email,
such as allowing a blog to accept new posts from an email (which could even
have been sent from a phone).</p>

<h2 id="label-Sending+emails">Sending emails</h2>

<p>The framework works by initializing any instance variables you want to be
available in the email template, followed by a call to <code>mail</code> to
deliver the email.</p>

<p>This can be as simple as:</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Notifier</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">ActionMailer</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>
  <span class="ruby-identifier">default</span> <span class="ruby-identifier">from</span><span class="ruby-operator">:</span> <span class="ruby-string">'system@loudthinking.com'</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">welcome</span>(<span class="ruby-identifier">recipient</span>)
    <span class="ruby-ivar">@recipient</span> = <span class="ruby-identifier">recipient</span>
    <span class="ruby-identifier">mail</span>(<span class="ruby-identifier">to</span><span class="ruby-operator">:</span> <span class="ruby-identifier">recipient</span>,
         <span class="ruby-identifier">subject</span><span class="ruby-operator">:</span> <span class="ruby-node">&quot;[Signed up] Welcome #{recipient}&quot;</span>)
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>

<p>The body of the email is created by using an Action View template (regular
<a href="../../classes/ERB.html">ERB</a>) that has the instance variables
that are declared in the mailer action.</p>

<p>So the corresponding body template for the method above could look like
this:</p>

<pre>Hello there,

Mr. &lt;%= @recipient %&gt;

Thank you for signing up!</pre>

<p>If the recipient was given as “david@loudthinking.com”, the email generated
would look like this:</p>

<pre>Date: Mon, 25 Jan 2010 22:48:09 +1100
From: system@loudthinking.com
To: david@loudthinking.com
Message-ID: &lt;4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail&gt;
Subject: [Signed up] Welcome david@loudthinking.com
Mime-Version: 1.0
Content-Type: text/plain;
      charset=&quot;US-ASCII&quot;;
Content-Transfer-Encoding: 7bit

Hello there,

Mr. david@loudthinking.com

Thank you for signing up!</pre>

<p>In previous version of <a href="../../classes/Rails.html">Rails</a> you
would call <code>create_method_name</code> and
<code>deliver_method_name</code>.  <a
href="../../classes/Rails.html">Rails</a> 3.0 has a much simpler interface
- you simply call the method and optionally call <code>deliver</code> on
the return value.</p>

<p>Calling the method returns a Mail Message object:</p>

<pre class="ruby"><span class="ruby-identifier">message</span> = <span class="ruby-constant">Notifier</span>.<span class="ruby-identifier">welcome</span>(<span class="ruby-string">&quot;david@loudthinking.com&quot;</span>)  <span class="ruby-comment"># =&gt; Returns a Mail::Message object</span>
<span class="ruby-identifier">message</span>.<span class="ruby-identifier">deliver</span>                                       <span class="ruby-comment"># =&gt; delivers the email</span>
</pre>

<p>Or you can just chain the methods together like:</p>

<pre>Notifier.welcome(&quot;david@loudthinking.com&quot;).deliver    # Creates the email and sends it immediately</pre>

<h2 id="label-Setting+defaults">Setting defaults</h2>

<p>It is possible to set default values that will be used in every method in
your Action Mailer class. To implement this functionality, you just call
the public class method <code>default</code> which you get for free from <a
href="../../classes/ActionMailer/Base.html">ActionMailer::Base</a>. This
method accepts a <a href="../../classes/Hash.html">Hash</a> as the
parameter. You can use any of the headers e-mail messages has, like
<code>:from</code> as the key. You can also pass in a string as the key,
like “Content-Type”, but Action Mailer does this out of the box for you, so
you won’t need to worry about that. Finally, it is also possible to pass in
a Proc that will get evaluated when it is needed.</p>

<p>Note that every value you set with this method will get overwritten if you
use the same key in your mailer method.</p>

<p>Example:</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">AuthenticationMailer</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">ActionMailer</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>
  <span class="ruby-identifier">default</span> <span class="ruby-identifier">from</span><span class="ruby-operator">:</span> <span class="ruby-string">&quot;awesome@application.com&quot;</span>, <span class="ruby-identifier">subject</span><span class="ruby-operator">:</span> <span class="ruby-constant">Proc</span>.<span class="ruby-identifier">new</span> { <span class="ruby-node">&quot;E-mail was generated at #{Time.now}&quot;</span> }
  <span class="ruby-operator">...</span><span class="ruby-operator">..</span>
<span class="ruby-keyword">end</span>
</pre>

<h2 id="label-Receiving+emails">Receiving emails</h2>

<p>To receive emails, you need to implement a public instance method called
<code>receive</code> that takes an email object as its single parameter.
The Action Mailer framework has a corresponding class method, which is also
called <code>receive</code>, that accepts a raw, unprocessed email as a
string, which it then turns into the email object and calls the receive
instance method.</p>

<p>Example:</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Mailman</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">ActionMailer</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>
  <span class="ruby-keyword">def</span> <span class="ruby-identifier">receive</span>(<span class="ruby-identifier">email</span>)
    <span class="ruby-identifier">page</span> = <span class="ruby-constant">Page</span>.<span class="ruby-identifier">find_by</span>(<span class="ruby-identifier">address</span><span class="ruby-operator">:</span> <span class="ruby-identifier">email</span>.<span class="ruby-identifier">to</span>.<span class="ruby-identifier">first</span>)
    <span class="ruby-identifier">page</span>.<span class="ruby-identifier">emails</span>.<span class="ruby-identifier">create</span>(
      <span class="ruby-identifier">subject</span><span class="ruby-operator">:</span> <span class="ruby-identifier">email</span>.<span class="ruby-identifier">subject</span>, <span class="ruby-identifier">body</span><span class="ruby-operator">:</span> <span class="ruby-identifier">email</span>.<span class="ruby-identifier">body</span>
    )

    <span class="ruby-keyword">if</span> <span class="ruby-identifier">email</span>.<span class="ruby-identifier">has_attachments?</span>
      <span class="ruby-identifier">email</span>.<span class="ruby-identifier">attachments</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attachment</span><span class="ruby-operator">|</span> 
        <span class="ruby-identifier">page</span>.<span class="ruby-identifier">attachments</span>.<span class="ruby-identifier">create</span>({
          <span class="ruby-identifier">file</span><span class="ruby-operator">:</span> <span class="ruby-identifier">attachment</span>, <span class="ruby-identifier">description</span><span class="ruby-operator">:</span> <span class="ruby-identifier">email</span>.<span class="ruby-identifier">subject</span>
        })
      <span class="ruby-keyword">end</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>

<p>This Mailman can be the target for Postfix or other MTAs. In <a
href="../../classes/Rails.html">Rails</a>, you would use the runner in the
trivial case like this:</p>

<pre>rails runner 'Mailman.receive(STDIN.read)'</pre>

<p>However, invoking <a href="../../classes/Rails.html">Rails</a> in the
runner for each mail to be received is very resource intensive.  A single
instance of <a href="../../classes/Rails.html">Rails</a> should be run
within a daemon, if it is going to process more than just a limited amount
of email.</p>

<h2 id="label-Configuration">Configuration</h2>

<p>The Base class has the full list of configuration options. Here’s an
example:</p>

<pre>ActionMailer::Base.smtp_settings = {
  address:        'smtp.yourserver.com', # default: localhost
  port:           '25',                  # default: 25
  user_name:      'user',
  password:       'pass',
  authentication: :plain                 # :plain, :login or :cram_md5
}</pre>

<h2 id="label-Download+and+installation">Download and installation</h2>

<p>The latest version of Action Mailer can be installed with RubyGems:</p>

<pre>% [sudo] gem install actionmailer</pre>

<p>Source code can be downloaded as part of the <a
href="../../classes/Rails.html">Rails</a> project on GitHub</p>
<ul><li>
<p><a
href="https://github.com/rails/rails/tree/master/actionmailer">github.com/rails/rails/tree/master/actionmailer</a></p>
</li></ul>

<h2 id="label-License">License</h2>

<p>Action Mailer is released under the MIT license:</p>
<ul><li>
<p><a
href="http://www.opensource.org/licenses/MIT">www.opensource.org/licenses/MIT</a></p>
</li></ul>

<h2 id="label-Support">Support</h2>

<p>API documentation is at</p>
<ul><li>
<p><a href="../../index.html">api.rubyonrails.org</a></p>
</li></ul>

<p>Bug reports and feature requests can be filed with the rest for the Ruby on
<a href="../../classes/Rails.html">Rails</a> project here:</p>
<ul><li>
<p><a
href="https://github.com/rails/rails/issues">github.com/rails/rails/issues</a></p>
</li></ul>

    </div>
  


  


  
  


  


  

  



  

    

    

    


    


    <!-- Methods -->
              </div>

    </div>
  </body>
</html>